home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / cmds / tar.gnu / sprite / tar.man < prev    next >
Encoding:
Text File  |  1992-03-28  |  7.9 KB  |  278 lines
  1. '\" Copyright 1992 Regents of the University of California
  2. '\" Permission to use, copy, modify, and distribute this
  3. '\" documentation for any purpose and without fee is hereby
  4. '\" granted, provided that this notice appears in all copies.
  5. '\" The University of California makes no representations about
  6. '\" the suitability of this material for any purpose.  It is
  7. '\" provided "as is" without express or implied warranty.
  8. '\" 
  9. '\" $Header: /sprite/lib/forms/RCS/cmd.man,v 1.4 92/03/02 15:20:18 bmiller Exp $ SPRITE (Berkeley)
  10. '/" 
  11. .so \*(]ltmac.sprite
  12. .HS TAR cmds
  13. .BS
  14. '\" Note:  do not modify the .SH NAME line immediately below!
  15. .SH NAME
  16. tar \- tape archiver
  17. .SH SYNOPSIS
  18. \fBtar\fR \fIoptions\fR [ \fIname ...\fR ]
  19. .SH COMMAND OPTIONS
  20. .IP "\fB\-c\fR" 15
  21. Create a new archive using the named files.
  22. .IP "\fB\-d\fR" 15
  23. Compare (``diff'') the contents of the archive with the named files.
  24. .IP "\fB\-r\fR" 15
  25. Append the named files to the end of the archive.
  26. .IP "\fB\-t\fR" 15
  27. ``Table of contents'' command: list the named files in the archive.
  28. .IP "\fB\-u\fR" 15
  29. ``Update'' command: like 
  30. .BR \-r ,
  31. except files are appended only if they aren't already in the archive or
  32. are newer than the version in the archive.
  33. .IP "\fB\-x\fR" 15
  34. Extract files from the archive.
  35. '\" .IP "\fB\-A\fR" 15
  36. '\" Concatenate multiple archives into one big archive (untested GNU
  37. '\" extension). 
  38. '\" .IP "\fB\-D\fR" 15
  39. '\" Delete files from the archive (untested GNU extension).  Don't use
  40. '\" on tapes.
  41. .IP "\fB\+version\fR" 15
  42. Display the version of
  43. .B tar
  44. that you're running.
  45. .SH GENERIC MODIFIER OPTIONS
  46. .IP "\fB\-b \fIblockSize\fR" 15
  47. Use a blocking factor of \fIblockSize\fR blocks per read or write
  48. (default 20).
  49. .IP "\fB\-B\fR" 15
  50. Ensure that the blocking factor is used.
  51. .IP "\fB\-f \fIfileName\fR" 15
  52. Name of the archive.
  53. .IP "\fB\-C \fIdirectory\fR" 15
  54. Change \fBtar\fR's current working directory to
  55. .IR directory .
  56. .IP "\fB\-e\fR" 15
  57. Enable debug output.
  58. '\" .IP "\fB\-M\fR" 15
  59. '\" Let the archive occupy multiple volumes (e.g., tapes or floppies)
  60. '\" (untested GNU extension).
  61. '\" .IP "\fB\-N \fIdate\fR" 15
  62. '\" Only work on files that are more recent than 
  63. '\" .I date
  64. '\" (untested GNU extension)
  65. .IP "\fB\-R\fR" 15
  66. Include the current record number when printing a message.
  67. .IP "\fB\-T \fIfileName\fR" 15
  68. Get the file list from
  69. .I fileName
  70. instead of from the command line.
  71. .IP "\fB\-v\fR" 15
  72. Verbose flag.
  73. .IP "\fB\-w\fR" 15
  74. Ask for confirmation before doing anything important.
  75. '\" .IP "\fB\-X \fIfileName\fR" 15
  76. '\" Exclude files using the globbing expressions read from
  77. '\" .I fileName 
  78. '\" (untested GNU extension).
  79. '\" .IP "\fB\-z\fR" 15
  80. '\" Keep the archive in compressed form (untested GNU extension).
  81. .SH OPTIONS FOR WRITING AN ARCHIVE
  82. '\" .IP "\fB\-G\fR" 15
  83. '\" Write special records to the archive for use in incremental dumps
  84. '\" (untested GNU extension).
  85. .IP "\fB\-h\fR" 15
  86. Write the target of a symbolic link, rather than the link itself.
  87. .IP "\fB\-l\fR" 15
  88. Don't cross filesystem boundaries when archiving a directory tree.
  89. .IP "\fB\-L\fR" 15
  90. Enable processing of files with long names (local extension).
  91. .IP "\fB\-n\fR" 15
  92. Don't recursively dump the contents of directories.
  93. .IP "\fB\-o\fR" 15
  94. Write the archive in a format that is compatible with very old
  95. versions of
  96. .BR tar .
  97. '\" .IP "\fB\-S\fR" 15
  98. '\" Be clever about sparse files (untested GNU extension).
  99. '\" .IP "\fB\-V\fR" 15
  100. '\" Write a volume header at the start of the archive (untested GNU extension).
  101. .IP "\fB\-W\fR" 15
  102. Verify the archive after writing it.
  103. .SH OPTIONS FOR READING AN ARCHIVE
  104. '\" .IP "\fB\-G\fR" 15
  105. '\" Used with incremental dumps.  Untested GNU extension.
  106. .IP "\fB\-i\fR" 15
  107. Ignore the usual 
  108. .B tar
  109. end-of-file marker in the archive.
  110. .IP "\fB\-k\fR" 15
  111. Don't overwrite existing files when restoring from the archive.
  112. '\" .IP "\fB\-K \fIfileName\fR" 15
  113. '\" Ignore entries before
  114. '\" .I fileName
  115. '\" in the archive (untested GNU extension).
  116. .IP "\fB\-m\fR" 15
  117. Use the current time as a file's modification time, rather than its
  118. modification time that was stored in the archive.
  119. .IP "\fB\-O\fR" 15
  120. Write the files' contents to
  121. .BR stdout ,
  122. rather than creating the files.
  123. .IP "\fB\-p\fR" 15
  124. Ignore the current user's
  125. .B umask
  126. when creating the files.
  127. .IP "\fB\-P\fR" 15
  128. Don't strip off the leading ``/'' (if any) in file pathnames.
  129. '\" .IP "\fB\-s\fR" 15
  130. '\" Promises that the file list is in the same order as the contents of
  131. '\" the archive (untested GNU extension).
  132. .BE
  133.  
  134. .SH DESCRIPTION
  135. .PP
  136. .B Tar 
  137. writes an archive file containing one or more files.  The
  138. version currently installed is derived from the GNU
  139. .BR tar ,
  140. with some local extensions.  All of the standard 
  141. .B tar 
  142. features are expected to work.  Not all GNU extensions are guaranteed
  143. to work.
  144. .PP
  145. The usual
  146. .B tar
  147. command syntax looks something like
  148. .DS
  149. tar cfb /dev/rst05.nr 20 /user2 /user3 /sprite/src/kernel
  150. .DE
  151. In this example,
  152. .B cfb 
  153. is the 
  154. .B c
  155. command, followed by two flags, 
  156. .B f
  157. and 
  158. .BR b .
  159. Following the 
  160. .B cfb 
  161. are flag arguments, in the order that the flags
  162. appeared 
  163. .RB ( /dev/rst05.nr
  164. for 
  165. .B f
  166. and 
  167. .B 20
  168. for 
  169. .BR b ).
  170. After the flag arguments are names of files or directories that are in
  171. (or are to be put into) the archive.  For some commands (e.g., 
  172. .B t
  173. and
  174. .BR x ) 
  175. the file name arguments are optional, in which case the operation is
  176. done on all files in the archive.  For directories, the name refers to
  177. all the files in the subtree rooted at that name.
  178.  
  179. The
  180. .B \-C
  181. flag is most useful when it appears in the middle of the file list,
  182. as in
  183. .DS
  184. tar cf /dev/rst05.nr -C /sprite/src kernel -C /sprite/src/lib include lib/c
  185. .DE
  186. It tells
  187. .B tar
  188. to change its working directory (e.g., to 
  189. .B /sprite/src
  190. and then later to
  191. .B /sprite/src/lib
  192. in the example above).
  193. File names that appear after the flag are interpreted relative to the
  194. working directory.
  195. For successive
  196. .B \-C
  197. commands, each directory name is relative to the directory name from
  198. the previous
  199. .B \-C
  200. command.
  201.  
  202. The meaning of the
  203. .B \-v
  204. flag depends on the command.  For the 
  205. .B c
  206. and
  207. .B x
  208. commands, 
  209. .B tar
  210. will print the name of each file as it is processed (normally 
  211. .B tar
  212. works silently).  For the
  213. .B t
  214. command,
  215. .B tar
  216. prints additional information about the file, such as its size,
  217. last-modification time, owner, etc.
  218.  
  219. Normally
  220. .B tar
  221. assumes that its read or write requests will maintain the requested
  222. blocking factor.  For some cases, for example when
  223. .B tar
  224. is in a pipeline that crosses a network, this is a bad assumption, and
  225. the user should include the
  226. .B \-B
  227. flag to ensure that blocking is done correctly.
  228.  
  229. If a file name begins with a slash (``/''), 
  230. .B tar
  231. will normally store the file name in the archive with the slash
  232. removed.  If the name in the archive contains a slash, 
  233. .B tar
  234. will normally ignore the leading slash when extracting the file from
  235. the archive.  To disable this feature (i.e., maintain the leading
  236. slash in absolute path names), use the
  237. .B \-P
  238. flag.
  239.  
  240. When creating an archive,
  241. .B tar
  242. detects hard links by checking the i-number and device-number for the
  243. current file name.  If another name with the same i-number and device-number
  244. has already been dumped, 
  245. .B tar
  246. marks in the archive that the current name is simply a hard link to
  247. that other name.  The file's contents are not written to the archive again.
  248. When extracting the file from the archive,
  249. .B tar
  250. simply recreates the link.  If the other name doesn't exist, 
  251. .B tar
  252. will report an error.  If the contents of the other name have changed
  253. since the archive was made, the link will refer to the new contents,
  254. not the contents on the archive.
  255.  
  256. .B Tar
  257. normally limits names to 100 characters.  When creating an archive, 
  258. .B tar
  259. will either truncate a long name or skip over the file completely,
  260. depending on circumstances.  To allow file name lengths up to the
  261. system limit, add the
  262. .B \-L
  263. flag when creating an archive.
  264.  
  265. GNU
  266. .B tar
  267. uses some fields in the per-file headers that are unused in other
  268. versions of
  269. .BR tar .
  270. Mumble more about compatibility with BSD tar, Posix.
  271.  
  272. .SH BUGS
  273.  
  274. -l doesn't work with Sprite, at least not without -h.
  275.  
  276. .SH KEYWORDS
  277. file, tape, archive
  278.